Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Td.man < prev next >

Wrap

Text File | 1990-04-09 | 43.5 KB | 927 lines

Td C Library Procedures Td _________________________________________________________________ NNAAMMEE Td_Create, Td_Delete, Td_PutRaw, Td_GetRaw, Td_ControlRaw, Td_Open, Td_Close, Td_PutCooked, Td_GetCooked, Td_ControlCooked, Td_CreatePdev, Td_DeletePdev - Terminal driver implementing 4.3 BSD operations. SSYYNNOOPPSSIISS ##iinncclluuddee <<ttdd..hh>> Td_Terminal TTdd__CCrreeaattee(_b_u_f_f_e_r_S_i_z_e, _c_o_o_k_e_d_P_r_o_c, _c_o_o_k_e_d_D_a_t_a, _r_a_w_P_r_o_c, _r_a_w_D_a_t_a) TTdd__DDeelleettee(_t_e_r_m_i_n_a_l) TTdd__PPuuttRRaaww(_t_e_r_m_i_n_a_l, _n_u_m_B_y_t_e_s, _b_u_f_f_e_r) int TTdd__GGeettRRaaww(_t_e_r_m_i_n_a_l, _n_u_m_B_y_t_e_s, _b_u_f_f_e_r) TTdd__CCoonnttrroollRRaaww(_t_e_r_m_i_n_a_l, _o_p_e_r_a_t_i_o_n) int TTdd__OOppeenn(_t_e_r_m_i_n_a_l, _s_e_l_e_c_t_B_i_t_s_P_t_r) TTdd__CClloossee(_t_e_r_m_i_n_a_l) int TTdd__PPuuttCCooookkeedd(_t_e_r_m_i_n_a_l, _n_u_m_B_y_t_e_s_P_t_r, _b_u_f_f_e_r, _s_i_g_N_u_m_P_t_r, _s_e_l_e_c_t_B_i_t_s_P_t_r) int TTdd__GGeettCCooookkeedd(_t_e_r_m_i_n_a_l, _p_I_D, _f_a_m_i_l_y_I_D, _n_u_m_B_y_t_e_s_P_t_r, _b_u_f_f_e_r, _s_i_g_N_u_m_P_t_r, _s_e_l_e_c_t_B_i_t_s_P_t_r) int TTdd__CCoonnttrroollCCooookkeedd(_t_e_r_m_i_n_a_l, _c_o_m_m_a_n_d, _i_n_p_u_t_S_i_z_e, _i_n_p_u_t, _o_u_t_p_u_t_S_i_z_e_P_t_r, _o_u_t_p_u_t, _s_i_g_N_u_m_P_t_r, _s_e_l_e_c_t_B_i_t_s_P_t_r) Td_Pdev TTdd__CCrreeaatteePPddeevv(_n_a_m_e, _r_e_a_l_N_a_m_e_P_t_r, _t_e_r_m_P_t_r, _r_a_w_P_r_o_c, _r_a_w_D_a_t_a) TTdd__DDeelleetteePPddeevv(_t_t_y_P_d_e_v) AARRGGUUMMEENNTTSS int _b_u_f_f_e_r_S_i_z_e (in) Size of output buffer to use for terminal. This is not an exact specification, in that the terminal driver may actu- ally allow more characters than Sprite v.1.0 Printed: April 9, 1990 1 Td C Library Procedures Td this to be buf- fered, but it will always allow at least this many characters to be buffered. int (*_c_o_o_k_e_d_P_r_o_c)() (in) Procedure to call for control opera- tions on cooked side of driver. ClientData _c_o_o_k_e_d_D_a_t_a (in) Additional value to pass to _c_o_o_k_- _e_d_P_r_o_c. int (*_r_a_w_P_r_o_c)() (in) Procedure to call for control opera- tions on raw side of driver. ClientData _r_a_w_D_a_t_a (in) Additional value to pass to _r_a_w_P_r_o_c. Td_Terminal _t_e_r_m_i_n_a_l (in) Token for termi- nal; must have been returned by some previous call to TTdd__CCrreeaattee. int _n_u_m_B_y_t_e_s (in) Total number of bytes to get or put for/from raw side of terminal. char *_b_u_f_f_e_r (in/out) Buffer containing characters to be written, or con- taining space in which to place characters being read. int _o_p_e_r_a_t_i_o_n (in) Control operation being invoked from raw side of termi- nal. Currently no operations are defined. int *_s_e_l_e_c_t_B_i_t_s_P_t_r (in/out) Points to word Sprite v.1.0 Printed: April 9, 1990 2 Td C Library Procedures Td whose bits (FFSS__RREEAADDAABBLLEE and FFSS__WWRRIITTAABBLLEE) indi- cate whether read or write opera- tions can complete successfully. Different pro- cedures may modify either or both of these bits. int *_n_u_m_B_y_t_e_s_P_t_r (in/out) Points to maximum number of bytes to read or write. Gets overwritten with actual number of bytes read or written. int *_s_i_g_N_u_m_P_t_r (out) Overwritten with signal number to apply to invoking process. Zero means no signal. int _p_I_D (in) Identifier of pro- cess invoking operation. int _f_a_m_i_l_y_I_D (in) Process group that _p_I_D belongs to. int _c_o_m_m_a_n_d (in) Number of IOCon- trol operation. Note: these are Sprite IOControl numbers, not UNIX ioctl numbers. See <<ddeevv//ttttyy..hh>> for definitions. int _i_n_p_u_t_S_i_z_e (in) Number of bytes of information in _i_n_p_u_t char *_i_n_p_u_t (in) Input buffer for IOControl opera- tion. Its struc- ture depends on the IOControl. Sprite v.1.0 Printed: April 9, 1990 3 Td C Library Procedures Td int *_o_u_t_p_u_t_S_i_z_e_P_t_r (in/out) Points to word specifiying total number of bytes of output buffer space available at _o_u_t_p_u_t. Modified to hold the actual number of output bytes provided by the IOControl. char *_o_u_t_p_u_t (in) Output buffer for IOControl opera- tion. Its struc- ture depends on the IOControl. char *_n_a_m_e (in) Name of file to use for terminal pseudo-device. May be either full name or root. char **_r_e_a_l_N_a_m_e_P_t_r (out) Where to store actual name of terminal pseudo- device used. NULL means _n_a_m_e is a root; non-NULL means _n_a_m_e is the full path name. Td_Terminal *_t_e_r_m_P_t_r (out) If non-NULL, token for terminal gets stored in the word pointed to by _t_e_r_m_P_t_r. Td_Pdev _t_t_y_P_d_e_v (in) Token for terminal-driven pseudo-device to destroy. Must have been returned previously by TTdd__CCrreeaatteePPddeevv. _________________________________________________________________ IINNTTRROODDUUCCTTIIOONN The Td library procedures implement a terminal driver with the same features as the terminal driver implemented in the 4.3 BSD kernel. The data structures managed by the Td library are called Td_Terminals and have two interfaces: Sprite v.1.0 Printed: April 9, 1990 4 Td C Library Procedures Td cooked and raw. The raw interface is used to communicate between the Td procedures and the low-level device corresponding to the terminal (usually a serial line device or a window on a screen). The cooked interface is used to communicate with processes accessing the 4.3-BSD-like termi- nal. In between, the Td library provides input and output character buffering, echoing and line editing, flow control, interrupt characters, and all the other features of the 4.3 BSD terminal driver. Each of the cooked and raw interfaces has at least four pro- cedures associated with it. Three of the procedures are provided by Td: one to pass characters into the terminal driver (e.g. a character that was just typed on the key- board, or a character that a user process wishes to ouput on the terminal), one to extract characters from the terminal driver (e.g. to pass them to a waiting user process, or to output them onto the terminal), and one to invoke control operations on the terminal. The fourth procedure for each interface is provided by the program in which Td is embed- ded. These procedures are called back by Td to notify the program of various events, for example, that characters are waiting in the terminal's output buffer, or that a full line is present in the terminal's input buffer. Most of the procedures in the Td library are generic in that they can be used in many different situations, including both user programs and the Sprite kernel. Two additional procedures, TTdd__CCrreeaatteePPddeevv and TTdd__DDeelleetteePPddeevv are provided to connect the cooked side of a Td_Terminal to a pseudo-device. These procedures are used by user-level Sprite programs like rrllooggiinndd and window-based terminal emulators. CCRREEAATTIINNGG AANNDD DDEELLEETTIINNGG TTEERRMMIINNAALLSS The TTdd__CCrreeaattee procedure is used to create a Td_Terminal. It returns a token that must be passed to most of the other Td procedures. Several Td_Terminals may exist at the same time, each created by a separate call to TTdd__CCrreeaattee. Each Td_Terminal corresponds to one logical terminal with its own input and output buffers. The _c_o_o_k_e_d_P_r_o_c and _r_a_w_P_r_o_c pro- cedures, and their associated ClientData values, are used to invoke control operations on the two sides of the terminal. The use of these two procedures is described in the sections below. The _b_u_f_f_e_r_S_i_z_e argument is described in the BBUUFFFFEERR-- IINNGG section below. TTdd__DDeelleettee simulates a hangup on a Td_Terminal, then destroys all of the state associated with the terminal. After it is called, the _t_e_r_m_i_n_a_l argument should never be used again by the caller. Sprite v.1.0 Printed: April 9, 1990 5 Td C Library Procedures Td RRAAWW IINNTTEERRFFAACCEE The raw interface is used to communicate between the termi- nal driver and the ``dumb'' terminal device. It consists of the three procedures TTdd__PPuuttRRaaww, TTdd__GGeettRRaaww, TTdd__CCoonnttrroollRRaaww, and the _r_a_w_P_r_o_c procedure passed to TTdd__CCrreeaattee. When characters are typed on the keyboard associated with the raw terminal, they should be passed to the temrinal driver by calling TTdd__PPuuttRRaaww. The Td library will then per- form input processing such as echoing and line editing. The procedure TTdd__GGeettRRaaww should be invoked to remove charac- ters from the terminal's output buffer and copy them to _b_u_f_f_e_r. The return value indicates how many characters were actually copied, up to either _n_u_m_B_y_t_e_s or the total number of characters in the output buffer. The return value is zero if the output buffer is empty. The caller of TTdd__GGeettRRaaww should then pass the characters to the raw serial device, or display them on the screen if the terminal is being emulated in a window. Note that it is up to the application in which Td is embedded to decide when to call TTdd__GGeettRRaaww. However, Td calls _r_a_w_P_r_o_c to notify the application that the terminal's output buffer contains characters; see below for details. The procedure TTdd__CCoonnttrroollRRaaww should be called when certain interesting events occur on the raw terminal. The _o_p_e_r_a_t_i_o_n argument identifies the event that occurred, and must be one of: TTDD__BBRREEAAKK Means that a break just occurred on the raw device. TTdd__CCoonnttrroollRRaaww should only be called when the break condition ends. TTDD__GGOOTT__CCAARRRRIIEERR Means that there is now carrier present on the raw device (e.g. a modem connection was just made). TTDD__LLOOSSTT__CCAARRRRIIEERR Means that carrier just went away on the raw device (e.g. the party on the other end hung up the phone). The Td module will invoke the procedure _r_a_w_P_r_o_c, which was passed to TTdd__CCrreeaattee, to ask for special actions on the raw terminal device, or to provide additional information that may be useful in managing the raw terminal device. _R_a_w_P_r_o_c must have the following structure: int rawProc(rawData, operation, inputSize, input, outputSize, output) Sprite v.1.0 Printed: April 9, 1990 6 Td C Library Procedures Td ClientData rawData; int operation; int inputSize; char *input; int outputSize; char *output; { ... } The _r_a_w_D_a_t_a argument will be the same as the _r_a_w_D_a_t_a argu- ment passed to TTdd__CCrreeaattee. It usually refers to a data structure describing the raw device, which will be used by _r_a_w_P_r_o_c. The _o_p_e_r_a_t_i_o_n parameter gives the reason for the call, the _i_n_p_u_t_S_i_z_e and _i_n_p_u_t arguments describe an area of data that Td is making available to _r_a_w_P_r_o_c, and _o_u_t_p_u_t_S_i_z_e and _o_u_t_p_u_t describe a buffer in which _r_a_w_P_r_o_c may place data that it wishes to return to Td. The return value from _r_a_w_P_r_o_c indicates how many bytes of data were actually placed at _o_u_t_p_u_t; it must not be greater than _o_u_p_t_u_t_S_i_z_e. At present, _o_p_e_r_a_t_i_o_n must be one of the following: TTDD__RRAAWW__SSTTAARRTT__BBRREEAAKK Initiate a break condi- tion on the raw device, if the device supports it. There is no input data or output data for this operation. TTDD__RRAAWW__SSTTOOPP__BBRREEAAKK End a break condition on the raw device, if the device supports it. There is no input data or output data for this operation. TTDD__RRAAWW__SSEETT__DDTTRR Set the ``data terminal ready'' condition on the raw device, if it sup- ports such an operation. There is no input data or output data for this operation. TTDD__RRAAWW__CCLLEEAARR__DDTTRR Clear the ``data terminal ready'' condition on the raw device, if it sup- ports such an operation. There is no input data or output data for this operation. TTDD__RRAAWW__SSHHUUTTDDOOWWNN The terminal has been Sprite v.1.0 Printed: April 9, 1990 7 Td C Library Procedures Td closed and is being shut down. The raw device should now be shut down too (e.g. hang up a modem). There is no input data or output data for this operation. TTDD__RRAAWW__OOUUTTPPUUTT__RREEAADDYY This operation indicates that the output buffer for the terminal has just become non-empty. At some point in the future, the application should invoke TTdd__GGeettRRaaww and out- put the characters to the device. There is no input data or output data for this operation. TTDD__RRAAWW__FFLLUUSSHH__OOUUTTPPUUTT If there are any charac- ters buffered for output on the raw device but not yet output, they should be discarded without out- putting them. There is no input data or output data for this operation. TTDD__RRAAWW__FFLLOOWW__CCHHAARRSS The flow-control charac- ters for the terminal have just been modified. The _i_n_p_u_t argument points to a structure with the following format: typedef struct { char stop; char start; } Td_FlowChars; Whenever _s_t_o_p is received from the raw terminal, output should be stopped until _s_t_a_r_t is received. _S_t_o_p and _s_t_a_r_t may be the same character. This call is made so that the driver for the raw device may implement flow con- trol directly in order to provide faster response Sprite v.1.0 Printed: April 9, 1990 8 Td C Library Procedures Td to the _s_t_a_r_t and _s_t_o_p characters. The raw dev- ice driver may ignore these calls and simply pass the flow control characters to the termi- nal driver, in which case Td will implement flow control, albeit with slower response. If either _s_t_o_p or _s_t_a_r_t is -1, then the raw driver must not implement flow control. There is no output data for this operation. TTDD__RRAAWW__SSEETT__BBAAUUDD__RRAATTEE Someone has just asked to change the baud rate for the device. Both the _i_n_p_u_t and _o_u_t_p_u_t argu- ments point to structures with the following for- mat: typedef struct { char ispeed; char ospeed; } Td_BaudRate; The iissppeeeedd and oossppeeeedd fields have the same values as they would in an ssggttttyybb structure, such as BB99660000. The _i_n_p_u_t argument gives the requested baud rates. _R_a_w_P_r_o_c may either accept these speeds or override them and return the actual speeds it used in the _o_u_t_p_u_t area. If the _i_n_p_u_t speeds are accepted, then _r_a_w_P_r_o_c need not modify the _o_u_t_- _p_u_t area; it can simply return 0. TTDD__RRAAWW__GGEETT__BBAAUUDD__RRAATTEE This operation is invoked to fetch the current input and output speeds for the raw device. Sprite v.1.0 Printed: April 9, 1990 9 Td C Library Procedures Td There is no _i_n_p_u_t area, but _o_u_t_p_u_t refers to a TTdd__BBaauuddRRaattee structure as described above for TTDD__RRAAWW__SSEETT__BBAAUUDD__RRAATTEE. _R_a_w_P_r_o_c should fill in the current speeds for the device at *_o_u_t_p_u_t and return ssiizzeeooff((TTdd__BBaauuddRRaattee)). CCOOOOKKEEDD IINNTTEERRFFAACCEE The cooked interface is used to communicate between the ter- minal driver and the processes wishing to access a device with full 4.3 BSD terminal semantics. As with the raw interface, it consists of a collection of Td procedures that the enclosing application invokes, plus one procedure in the enclosing application that Td invokes. Whenever a process attempts to open the terminal device, the procedure TTdd__OOppeenn should be called. If the terminal is in ``exclusive'' mode (meaning opens are being refused), then a UNIX error number is returned. Otherwise zero is returned and the FFSS__RREEAADDAABBLLEE and FFSS__WWRRIITTAABBLLEE bits of *_s_e_l_e_c_t_B_i_t_s_P_t_r are set to indicate whether there are input characters or output buffer space available, respectively. When the terminal is closed, TTdd__CClloossee should be invoked. There should be exactly one TTdd__CClloossee call for each TTdd__OOppeenn call: if an open stream is dduupp-ed, TTdd__CClloossee shouldn't be called until the last dduupp-ed copy is closed. When a process writes data to the cooked terminal, TTdd__PPuuttCCooookkeedd should be invoked to pass the data to the ter- minal driver. The characters will be added to the terminal's output buffer after performing output processing on them. The return value is always zero (meaning that the characters are always accepted). The FFSS__WWRRIITTAABBLLEE bit in *_s_e_l_e_c_t_B_i_t_s_P_t_r will be updated to reflect whether the terminal's output buffer is now ``full'' (see the BBUUFFFFEERRIINNGG section below for more on what this means). If so, then no more calls should be made to TTdd__PPuuttCCooookkeedd until the terminal driver gives notice that there is more space in the output buffer (this is done by calling _c_o_o_k_e_d_P_r_o_c as described below). TTdd__PPuuttCCooookkeedd overwrites the value at *_s_i_g_N_u_m_P_t_r; if the value written is non-zero then it is a UNIX signal number that should be applied to the calling process. When a process wishes to read characters from the cooked terminal, TTdd__GGeettCCooookkeedd should be called. This procedure will remove characters from the terminal's input buffer (up Sprite v.1.0 Printed: April 9, 1990 10 Td C Library Procedures Td to *_n_u_m_B_y_t_e_s_P_t_r of them) and copy them to _b_u_f_f_e_r. The value at *_n_u_m_B_y_t_e_s_P_t_r will be updated to reflect the actual number of characters returned. The return value from TTdd__GGeettCCooookkeedd will normally be zero; if an error occurred, then the return value will be a UNIX error number. If the terminal's input buffer is empty, then the return value will be EEWWOOUULLDD-- BBLLOOCCKK and *_n_u_m_B_y_t_e_s_P_t_r will be set to zero. The FFSS__RREEAADDAABBLLEE bit of *_s_e_l_e_c_t_B_i_t_s_P_t_r will be updated to reflect whether there are still more characters ready in the terminal's input buffer. TTdd__PPuuttCCooookkeedd overwrites the value at *_s_i_g_- _N_u_m_P_t_r; if the value written is non-zero then it is a UNIX signal number that should be applied to the calling process (this is used, for example, to generate SSIIGGTTTTIINN signals). When a process invokes an IOControl operation on the termi- nal, TTdd__CCoonnttrroollCCooookkeedd should be called. The arguments to TTdd__CCoonnttrroollCCooookkeedd indicate the IOControl number (_c_o_m_m_a_n_d), plus an input buffer (_i_n_p_u_t_S_i_z_e and _i_n_p_u_t) and an output buffer (*_o_u_t_p_u_t_S_i_z_e_P_t_r and _o_u_t_p_u_t). The value at *_o_u_t_p_u_t_- _S_i_z_e_P_t_r will be modified to reflect the actualy number of bytes of output data written at _o_u_t_p_u_t (this will be no more than the original value of *_o_u_t_p_u_t_S_i_z_e_P_t_r). The contents of the input and output buffers are determined by the specific _c_o_m_m_a_n_d being requested. See the documentation on the 4.3 BSD terminal driver for details. TTdd__CCoonnttrroollCCooookkeedd will modify the FFSS__RREEAADDAABBLLEE and FFSS__WWRRIITTAABBLLEE bits of *_s_e_l_e_c_t_- _B_i_t_s_P_t_r to reflect the state of the terminal's input and output buffers when the IOControl completes. TTdd__PPuuttCCooookkeedd overwrites the value at *_s_i_g_N_u_m_P_t_r; if the value written is non-zero then it is a UNIX signal number that should be applied to the calling process. The Td library will invoke the _c_o_o_k_e_d_P_r_o_c, which was passed as an argument to TTdd__CCrreeaattee, when it wishes to give notice of interesting events related to the cooked side of the ter- minal. _C_o_o_k_e_d_P_r_o_c should have the following structure: int cookedProc(cookedData, operation, inputSize, input, outputSize, output) ClientData cookedData; int operation; int inputSize; char *input; int outputSize; char *output; { ... } The _c_o_o_k_e_d_D_a_t_a argument will be the same as the _c_o_o_k_e_d_D_a_t_a argument passed to TTdd__CCrreeaattee. It usually refers to a data structure describing the interface to processes using the cooked terminal. The other arguments to _c_o_o_k_e_d_P_r_o_c and its Sprite v.1.0 Printed: April 9, 1990 11 Td C Library Procedures Td result have the same meaning as the arguments and result for _r_a_w_P_r_o_c, except that _o_p_e_r_a_t_i_o_n has different meanings. The values currently defined for _o_p_e_r_a_t_i_o_n are: TTDD__CCOOOOKKEEDD__SSIIGGNNAALL A signal should be gen- erated for the control- ling process group asso- ciated with the terminal. _I_n_p_u_t will point to a structure with the fol- lowing format: typedef struct { int sigNum; int groupID; } Td_Signal; The _s_i_g_N_u_m field gives a UNIX signal number (e.g. SSIIGGIINNTT), and _g_r_o_u_p_I_D identifies the control- ling process group for the terminal. _C_o_o_k_e_d_P_r_o_c is not expected to return any output data. TTDD__CCOOOOKKEEDD__RREEAADDSS__OOKK There is now readable data in the input buffer associated with the ter- minal, so that the next call to TTdd__GGeettCCooookkeedd will not return EEWWOOUULLDDBBLLOOCCKK. If there is a waiting process, it should prob- ably be woken up. There is no input data or out- put data for this opera- tion. TTDD__CCOOOOKKEEDD__WWRRIITTEESS__OOKK The output buffer for the terminal is now empty. If there is a process waiting to do output, it should probably be woken up. There is no input data or output data for this operation. PPSSEEUUDDOO--DDEEVVIICCEE IINNTTEERRFFAACCEE The Td library also contains routines to connect the cooked side of a terminal to a pseudo-device. The pseudo-device Sprite v.1.0 Printed: April 9, 1990 12 Td C Library Procedures Td routines use the facilities of the Pdev library, which in turn requires that the application use the FFss__SSeelleecctt library to manage I/O channels. The non-pseudo-device portions of the Td library may be used without also using FFss__SSeelleecctt. TTdd__CCrreeaatteePPddeevv creates a pseudo-device file and arranges for the file to have terminal-like behavior by associating it with a terminal managed by the Td library. Once TTdd__CCrreeaatteePPddeevv has been called, the pseudo-device and the cooked side of its terminal will be managed automatically. However, it is up to TTdd__CCrreeaatteePPddeevv's caller to manage the raw side of the pseudo-terminal. The _r_a_w_P_r_o_c and _r_a_w_D_a_t_a arguments to TTdd__CCrreeaatteePPddeevv are the same as the corresponding arguments to TTdd__CCrreeaattee (TTdd__CCrreeaatteePPddeevv passes them to TTdd__CCrreeaattee when it creates the terminal). If the _t_e_r_m_P_t_r argument to TTdd__CCrreeaatteePPddeevv is not NULL, then TTdd__CCrreeaatteePPddeevv stores the Td_Terminal token for the pseudo-terminal at *_t_e_r_m_P_t_r; this allows the application to invoke procedures like TTdd__PPuuttRRaaww. The name of the pseudo-device file created by TTdd__CCrreeaatteePPddeevv may be specified in either of two ways. If the _r_e_a_l_N_a_m_e_P_t_r argument to TTdd__CCrreeaatteePPddeevv is NULL, then the _n_a_m_e argument gives the complete name of the pseudo-device file. If _r_e_a_l_- _N_a_m_e_P_t_r is not NULL, then the pseudo-device file will be created in a host-specific directory for the machine on which the program is running, and the file name will have the form _n_a_m_e_X_X, where _X_X is a small integer chosen to avoid conflict with other files that have the same _n_a_m_e. A pointer to the complete name will be stored in *_r_e_a_l_N_a_m_e_P_t_r; the storage for the name is allocated by mmaalllloocc and should eventually be freed by TTdd__CCrreeaatteePPddeevv's caller. TTdd__CCrreeaatteePPddeevv normally returns a token for the pseudo- terminal. If the pseudo-device couldn't be opened, then NULL is returned and the variable ppddeevv__EErrrroorrMMssgg points to a string describing what went wrong. The only use for the token returned by TTdd__CCrreeaatteePPddeevv is to pass it to TTdd__DDeelleetteePPddeevv. When this happens, the pseudo- device is closed and the associated terminal is destroyed by calling TTdd__DDeelleettee. BBUUFFFFEERRIINNGG The input buffer for a Td_Terminal grows automatically to accommodate as much data as is present: there is no upper limit on its size. The output buffer will also grow automatically: TTdd__PPuuttCCooookkeedd always accepts all the data passed to it. However, it is usually a bad idea to buffer a very large number of characters on output, since these char- acters will have to be output even if the process is killed Sprite v.1.0 Printed: April 9, 1990 13 Td C Library Procedures Td with a control-C. The _b_u_f_f_e_r_S_i_z_e argument to TTdd__CCrreeaattee specifies a nominal output buffer size; whenever more than this many characters are buffered, TTdd__PPuuttCCooookkeedd will turn off the FFSS__WWRRIITTAABBLLEE bit in *_s_e_l_e_c_t_B_i_t_s_P_t_r to indicate that the buffer is nominally full; the enclosing application should then refuse to accept more characters for output (e.g., by suspending the process). When the output buffer empties, _c_o_o_k_e_d_P_r_o_c will be invoked with a TTDD__CCOOOOKKEEDD__WWRRIITTEESS__OOKK command. EEXXAAMMPPLLEESS The best way to learn how to use the Td library is to look at examples in the Sprite source code. The simplest example is the mmkkttttyy program; other examples are rrllooggiinndd (the remote-login server) and ttxx (a window-based terminal emula- tor). KKEEYYWWOORRDDSS 4.3 BSD, pseudo-device, terminal driver Sprite v.1.0 Printed: April 9, 1990 14